How to size a spend cap

The first question on almost every onboarding call is some version of "what is this going to cost us?" The honest answer is that it depends on two numbers you already have and one multiplication. This guide walks through it, then covers where to set the cap and what happens when you reach it.

The arithmetic

Canary bills per preview-hour: one hour that one preview is awake. Previews sleep after 30 idle minutes and cost nothing while asleep. So a month costs:

pull requests a month
  x hours each preview is awake
  x $0.19

The first number is on your Git host's insights page. The second is the one people overestimate. A preview is not awake for as long as its pull request is open. It is awake while it builds, while someone has it open, and for 30 minutes after the last request. Across workspaces that comes to a little over three hours per pull request. Theo's post on sleep and wake covers exactly what counts.

A worked example

Halyard has 38 engineers. In a typical month they open 214 pull requests, and each preview is awake for about 3.1 hours of its life.

214 pull requests  x 3.1 hours = 663 preview-hours
663 preview-hours  x $0.19     = $125.97

That is $125.97 for the month, a little over $3 an engineer, though we do not charge per engineer, and the designers and product managers who open those previews are free. With an annual commitment the rate is $0.15, which brings the same month to $99.45.

Adjusting for your team

Three things move the awake hours up or down.

• Pushes per pull request. Each push rebuilds only the services that changed, but the preview is awake while it does. A team that pushes fifteen small commits to a branch runs higher than one that pushes four.
• Who reviews. Every extra reviewer is another visit and another 30-minute tail. If designers and QA are in most reviews, plan for closer to four hours than three.
• The sleep setting. sleep_after: 30m is the default. Dropping it to 10m trims the tail after every visit, at the cost of a few more four-second wakes.

If you have no data yet, use four hours for the first estimate. It is wrong in the safe direction.

Where to set the cap

preview:
  budget:
    monthly_usd: 200

The cap is a ceiling, not a commitment. You pay for the hours you use and nothing for the headroom. So the cap does not need to be close to the estimate. It needs to be a number that would mean something has gone wrong.

A good starting point is one and a half times the estimate, rounded up to something easy to say. For a Halyard-sized team that is $200 against an expected $126. A normal month never gets near it. A branch with a job that pings itself every minute and never sleeps would reach it, and that is the case the cap is there for.

Because the cap lives in canary.yml, changing it is a pull request. Someone reviews it, and there is a record of who raised it and why.

What happens at the cap

1. At 80%, workspace admins get a notice by email, and in Slack if it is connected.
2. At 100%, awake previews are put to sleep and new ones are not built. Open pull requests get a comment saying the cap was reached and who can raise it.
3. Nothing is torn down. Volumes, links and data stay where they are. Raise the cap, or wait for the first of the month, and previews wake as usual.

Hitting the cap never deletes work and never produces an overage. The bill for the month is the cap, at most.

Why Oxbow picked $400

Oxbow has 64 engineers and came to Canary from two staging clusters that cost $2,140 a month whether anyone used them or not. Sam Rivera, their head of platform, ran the arithmetic above and got an estimate near $300.

He set the cap at $400. It was comfortably above the estimate, and it was less than a fifth of the old bill, so nobody in finance needed a meeting to approve it. Their average month has come in at $312. The cap has not been reached.

That is the pattern worth copying. Pick the number by asking what you would be willing to explain, not what you expect to spend.

The Hobby plan includes 500 preview-hours a month. At 3.1 awake hours each, that is roughly 160 pull requests, which is enough to measure your own number on one real repository before you set any cap at all. The rates and what each plan includes are on the pricing page, and the docs list every key under budget.